DDDDDDDDDDDD EEEEEEEEEEEEEEE BBBBBBBBBBBB UUU UUU GGGGGGGGGGGG 
DODDDDDDDDDD EEEEEEEEEEEEEEE BBB888BB8BBBB UUU UUU GGGGGGGGGGGG 
DDDDDDDDDDDD EEEEEEEEEEEEEEE B8BB8BB8BBEB UUU UUU 666666666666 
DOD | DDD EEE BBB BBB UUU UU G 

DOD DDD EEE BBB BBB UUU UUU GGG 

DDD DDD EEE 888 BBB UUU UUU GGG 

DOD DOD EEE BBB BBB UUU UUU GGG 

DDD DOD EEE 888 BBB UUU UUU GGG 

DOD DDD EEE BBB BBB UUU UUU GGG 

DOD DDD EEEEEEEEEEEE BBBBBBBBBBBB UUU UUU GGG 

DDD DDD EEEEEEEEEEEE BBBBBBBSBBBBB UUU UUU GGG 

DOD DDD EEEEEEEEEEEE BBBBBBBBBBBB UUU UUU GGG 

DOD DDD EEE BBB UUU UUU GGG 666666666 
DDD DDD EEE B88 BBB UUU UUU GGG 666666666 
DOD DDD EEE BBB BBB UUU UUU GGG 666666666 
DDD DDD EEE 888 BBB UUU UUU GGG GGG 
DOD DDD EEE BBB BBB UUU UUU GGG GGG 
DOD DDD EEE BBB BBB UUU UUU GGG GGG 
DDDDDDDDDDDD EEEEEEEEEEEEEEE B88B8BB8B888 UUUUUUUUUUUUUUU GGGGGGGGG 
DDDDDODDDDDD EEEEEEEEEEEEEEE BBSBBBB8BBBB UUUUUUUUUUUUUUU GGGGGGGGG 
DDDDDDDDDDDD EEEEEEEEEEEEEEE BBBBBBBBBBBB UUUUUUUUUUUUUUU GGGGGGGGG 


#*F ILE®*1D**DBGEXT 
DDDDDDDD + —«- BBBBBBBB GGGGGGGG EEEEEEEEEE xx XX TTTTTTTTTT 
DDDDDDDD = BBBBSBBB GGGGGGGG EEEEEEEEEE XX XX TTTTTTTTTT 
dD DD 8B BB GG EE XX XX TT 
dD DD 8B BB GG EE XX x TT 
0D DD 6B BB GG EE XX = MX TT 
dD 0D 8B 8B GG EE XX XX 1T 
DD DD BBBBBBBB GG EEEEEEEE XX 1T 
DD 0D BBBBBBBB 6G EEEEEEEE XX TT 
DD DD BB BB GG GGGGGG EE XX XX tT 
DD DD 8B BB GG GGGGGG EE XX XX TT 
DD DD 8B 88 GG GG EE XX XX TT — 
dD oD 88 GG GG EE XX XX TT — 
DDDDDDDD ~=©=—-_—- BBBBBBBB GGGGGG  EEEEEEEEEE Xxx XX TT ote: 
DDDDDDDD = BBBBBBBB GGGGGG  EEEEEEEEEE Xx XX TT * 
RRRRRRRR = EEEEEEEEEE o00000 
RRRRRRRR EEEEEEEEEE QQQQ0Q 
RR RR EE aa 
RR RR EE aa aa 
RR RR EE ao aa 
RR RR EE aa aa 
RRRRRRRR EEEEEEEE QQ QQ 
RRRRRRRR EEEEEEEE Q QQ 
RR RR EE ag aa aa 
RR RR EE QQ QQ QQ 
RR RR EE Q Q 
RR RR EE ao aa 
RR RR EEEEEEEEEE 0000 00 
RR RR EEEEEEEEEE  Q000 a0 
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: DBGEXT.REQ 
Version: *v04-000' 
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ONLY IN ACCOR WITH THE TERMS SUCH LICENSE AND WITH THE 
INCLUSION OF THe ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER 
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY 
Fuensrekatee NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY 


phe INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE W 
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CORPORATION. 


DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 


ITHOUT NOTICE 
TAL EQUIPMENT 
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WRITTEN BY 
Rich Title October 1983 
MODIFIED BY 
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MODULE FUNCTION 


This module contains the definitions for the control blocks 
that are used in communications between DEBUG and the 

ADA multi-tasking run-time system. These same definitions will be 
extended for use in communication with the PPA multi-tasking 
system and other run-time systems, at a future time. 


® 
® 
* 
® 
® 
* 
* 
® 
® 
* 
® 
® 
® 
® 
® 
® 
® 
® 
® 
® 
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EXTERNAL CONTROL BLOCK 


An “External Control Block’ is a data structure that can be used 
' when DEBUG needs to call a routine that is not Linked in as 
! part of the DEBUG image. 


For example, DEBUG will have commands to support ADA ay es dm - 
i However, DEBUG has no knowledge of the workings of the ADA mutli-tasking 
; Syptee and the data structures that describe tasks. Instead, DEBUG 

will call a routine in the ADA multitasking system in the course 
! of processing SHOW TASK, SET TASK, or any other command that requires 
knowledge about tasks. 


There will be a fey bo gntry pete ADASDBGEXT, in the ADA Suietseen ing 

' system which is called by DEBUG. fhe xternal Control Block is the only 

! parameter. Similarly, other multitasking run-time systems will have a 

: oSapie entry point, of the form <facility>SDBGEXT, with the entry point 
taking an External Control Block as its single parameter. In general, 

! the External Control Block can be used as a means of communication with 

! run-time systems that are not part of DEBUG. For example, in debugging 

the | SCAN we may want to allow the user to set breakpoints on 

' events such as a SCAN pattern-match. The External Control Block will 

be ed data structure that we use to communicate with the SCAN run-time 

system. 


The DBGEXTSV_FACILITY_ID field identifies which run-time system is being 
! called. The VAX/VMS 34 code is used. Thus, it is assumed that 

there will be at most one DBGEXT entry point in the run-time code of any 
facility. Currently, legal values are the facility codes for ADA, PPA, 
and SCAN. This field may not actually be looked at (if desired, the 
run-time system may do a sanity check for the right value). 


Since there are several functions we want each run-time system 
to perform for us, there is a DBGEXTSW_FUNCTION_CODE field 
which specifies which function is to be performed. 


ALL functions return a status code in the DBGEXTSL_STATUS field. 
For all functions, there is a DBGEXTSL_FLAGS field which can be used 
+4 S of flags. The exact use of these flags depends on 

e function. 


The use of the remaining fields of the data structure Gopgnes upon 
! the “FACILITY_ID" field and upon the ‘‘FUNCTION_CODE" field. 


NOTE: DEBUG makes these calls with ASTs disabled, It is required 
! that the run-time code not reenable ASTs during its execution. 
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i The follow illustrates the header of an External Control Block. 
: The fields o External Control Block are then illustrated 
! for the case where the “FACILITY_1D" is “‘ADA’. 


1 
1 
1 
1 
1 
1 
The following header is common to all External Control Blocks: 
1 
1 
1 
1 
' 
1 
1 
1 
1 


‘unused | V_FACILITY_ID { DBGEXTSW_FUNCTION_CODE | 


—— — ———— —— ——— tne + 


H DBGEXTSL_STATUS H 


Gececenccousesowcsoocseessesooosseseossoeosesesesoco a 


i (some flags unused) DBGEXTSL_FLAGS : 


Geooeceesceoooweewoososcowoooeresooseecocoocecccocces 
‘ 


: reserved for future use : 


$enrwew nen en ewme rena eeeoeoe See e ee eee 2 — — — — — came me sae + 


wn —- O 
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oonoevw fF wNH — Oo 


fol Lowi 
d 


is ‘ADA’. This control block is use 


most — Be. (some functions, e.g. GET_REGISTERS and SET_REGISTERS 


a longer control block, displayed later)? 


— yg Beg Pe me ee 2S mona wren eno warwzreanrnrron een nae * 


‘unused : V_FACILITY_ID { DBGEXTSW_FUNCTION_CODE ; 


ere FI th lee I ct hatte Bt ee tl ae, tes > 


H DBGEXTSL_STATUS ' 


Guoeeeecousssecesecesenessesoscosescesoscoosesecceso + 


i(some flags unused) DBGEXTSL_FLAGS : 


4 


reserved for future use : 


Fewer ewn cme wm ma wreanwronr mn nen co wmenens eres enema nwewoeweoae + 


: DBGEXTSL_TASK_VALUE ' 


+ eueeuceeseseoeusesoceeesesso —— ⏑— + 


‘ DBGEXTSL_TASK_NUMBER i 


twee were emer eo mm wenn woe ceri ew mew O ERE mM e MERE owes sean m + 


‘unused :V_HOLD: V_STATE {| DBGEXTSW_SPECIFIED_FLAGS: 


— —— meen lesa! oh. teen. + 


' DBGEXTSV_PRIORITY ' 


9888988858800 08SEeSSOOeTeCEsSeeeESooneeserese + 


: DBGEXTSL_PRINT -ROUTINE i 


—— ſſ — — n eae awn eon coa$ 


' DBGEXTSL -EVENT_ID 


wees ese ee Be TBO we EMBED Ee Dee Oe aunesenesuesoesoocoosses$ 


Whee trotes the control oak when the FACILITY_ID 


1 
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' 
* 
— 
. 
' 
. 
' 
. 
' 
. 
— 
* 
— 
— 
. 
1 
. 
‘ 
. 
' 
. 
' 
: 
J 
— 
— 
. 
— 
— 
. 
J 
. 
] 
. 
' 
. 
J 
. 
' 
° 
' 
. 
— 
— 
— 
— 
— 
— 
— 
— 
‘ 
° 
' 
. 
4 
. 
' 
. 
‘ 
. 
— 
' 
. 
— 
J 
— 
— 
. 
‘ 
. 
‘ 
Ps 
' 
. 
i] 
. 
‘ 
. 
4 
. 
i 
. 
‘ 
. 
‘ 
. 
J 
. 
J 
— 
‘ 
. 
! 
. 


The following —243 ar 


ADA’ a 


ind th 


is passed in. 


oon oe uw Fe WwNH =| OC 


ae wo og wo ae — ot 


— aga TO + TE a: gig neta age ere em panetag eseeceoe > 


tumused | V_FACILITY_ID { DBGEXTSW_FUNCTION_CODE | 


Seamer MIN cee a= Sal a I acsearle co oe te ie 


H DBGEXTSL_STATUS ' 


deoceeceouseseeseuesconesoesoeecsoosswencoseeoeesese + 


i(some flags unused) DBGEXTSL_FLAGS ' 


—————— * 
‘ 


: reserved for future use ' 


omen e meen eo ene ner one OE EEO ENS ES Se Demet awooaman — 


DBGEXTSL_TASK_VALUE ' 


po ae —— 
funused iv.WOUDi 1 DBGENTSU_SPECIFIED_FLAGS! 
acne aus 
H DBGEXTSL_PRINT “ROUTINE H 
— — 
— — —— Re ae ER RE BOTTI ; 
— AS, 
ALT RON — ed 
RS ee PT ON : 
DBGEXTSL_R4 
Sane Meco Openers H 
ae 
‘We 
RAITT I PANS 
DBGEXT$L_R9 ; 
‘eae ree, 


‘ DBGEXTSL_R11 


Gewese ere see woe ewe crema wee eer ere wre woe se ewe wen eon eee cee + 


DBGEXTSL_AP ; 


gwen seen we awe Swe mtr ene enw owe meee — wmrreroe eos + 


he smaller block (without the register fields) 
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DBGEXTSL_FP ' 


— nam ace wenn ene seen em e ome ema moo as = + 

‘ DBGEXTSL_SP H 
‘ DBGEXTSL_PC H 
DBGEXTSL_PSL ' 


¢eeeeonenn en en eee ewe wee ee ee ON eM Se De meee — eecoae + 


Va 
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'¢ 
; CONTROL BLOCK FIELDS 


rome DBGEXTSHEADER_FIELDS = 


DBGEXTSW_ FUNCTION_CODE = o owe 18 8 ° 
DBGEKTSV. sh ACILITY. ID = ° iB. is 037 

= oe ° e e 
bBGEKTSL STATUS eit, 8. Me Ge 
DBGEXTSL_FLAGS = ° 8. 32, 9}. 

DBGERTSV_ALL = » O. 1, OJ, 2°(WHAT WILL ALL DO?-tbs))% 
DBGEXTSV_FULL = ~ 1, 1, 03,%¢Cexplain FULL -tbs))% 
pogextey _PSEUDO_GO et 2 2@ Ys We 
' Pseudo=go is Set by the run-time system on return to DEBUG to 


! indicate that DEBUG must do a 2 peau do-GO to accomplish the function. 
! Used only for function SET_ACTIVE (see discussion under SET_ACTIVE). 


DBGEXTSV_NO_HEADER ‘th 3 Tt @ 

! Suppresses output of headers on a SHOW_ TASK, SHOW_STATISTICS, 
! or SHOW _DEADLOCKS. 

! reserved E 0, 4, $8. 0], 
! reserved 4, 0, 32, 0J, 


song" Me FIELDS = 


GEXTSL_TASK_VALUE e{é § NH. Biz 

OO CE ~TASK_ SE S, Gs ee Gite 
DBGE XT$W Spectr ieD FLAGS ={€6, O, 16, 0], 
DBGERTSV_HOLD SPECIFIED et 6, 8. ts Ole 
DBGEXTSV_ sii N13 SPECIFIED ot B.- Be Se Be 
DBGEXTSV_ “PRIORTTY_SPECIFIED = 6. ¢° 13° 63° 

. e = o e e oe 
DBGEXTS$SV_STATE = (6, 16, 4, 0], 
DBGERTS$V_STATE_RUNNING et 6G. Ws Te Ge 
DBGEXT$V_STATE_REA ee @. Sirs we bi. 
DBGEXT$V_STATE_ SUSPENDED o£ Gy Tee. Be Whe 
DBGEXTSV7 STATE_ TERMINATED ={ 6, 19, 1, 0J, 
DBGEXT$v_HOLB =f 6, $0. 1, 8 
' reserved = g. s Wee - 
DBGEXT$L_PRIORITY = " 8. 32, OJ, 
DBGERTSV PRIORITY 00 “2 So ag mh 
DBGEXTS$V_PRIORITY_01 oe ey Be ee We 

pose Tey pe iOnt tvs ={ 7, ¢ ay Ole 
DBGEXTSV_PRIORITY_ ot 2. we Be Whe 

— 83— oe — 0 
GEXTSV_PRIORITY_05 — © Mim 7s we 
DBGEXTSV_PRIORITY_06 at fs g. ', Os, 
DBGEXTSV~PRIORITY~0 “2 & ee a eS — 
DBGEXTS$V_PRIORITY_08 sf{ 7, g. 1, 0), 
DBGEXT$V_ PRIORITY 09 EVs Ba Va Ode 


14 
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se &@ 8 8 F&F FF Ff 
De) ee) |) | | |e | | ee | 
öOOSOSSOOIOODOOOIOOIS G SS OOOOOOOSOOCOOOO 

88———————2 F&F F&F FB 
SE EOIN 

ses ®@ 8 8 &8@e te 8&e 8&8 F 0 
OK CM TNOPR. DOO CUM TFN OK. DOOr- OO 
Se ee ee ee ee ee ee ee) 


see 8eeeeeeeesteteste# 8 &@& et &© & &©& & © & 8 


REPRE PELE PRR ERR RRR. OO 
CR LI tts tis 
Hunnnnnnnnnnnnnnnnnnnnnn 


OM VUMNTNOP- DOO UM TN OR- DAO 


oooooeeooeo 


@Qaacaacacacaacaacaacaacacaaac i 1 
O2qgagaagaOAAAAAOAAAOAAOA404400rr 


eeeceeceececececeec eee ee eee ts ee 
S>rorrerer>>> > > 3 >> >>> 2>2>2>27> >> —-W 
PAPAAPAAAAA ABABA AAAAAARAAAAR > 
i i ee ee ee ol 
>< OK OK OK OK OK OK OK OK OK OE OE OK OK OK OK OK OK OK KKK CC 
dd a a a 
VVIVOSVOIVIIS BOVIS VVIVVIoe#e 
+4 

28 


TES; 
FIELD DBGEXTSREG 


FIELDS = 


SET 


esse eeeeeseeeeeas 
Se | | ge | | |e | | |) | 
COoooooooooooooooeo 


ese eee eeseeese eee eee 
cucucucucucucucucucucucucuCuCuCun 
EET 


ese @seeeseeeeeteese8 &8® &® &©® & & 


OOOOOIOOOIOIOOIDCOOIOIOẽOSOOGO 


— — — ——2222—222222222 
OM UM TNOR.DOOOK— UM TNO 
ek eel ee el od ed ed ed ek oe 
I ⏑ ⏑ ⏑ ⏑ ⏑ ⏑ ⏑ ⏑ ed ed oad —— 


V_ 
— 
See ees 
RAAAAAAAAAAAAAAAA 
DB ee ee 
rivivintninivtvintntnietetntntete 
VIOVGOVOVOVVOVVESEE99 
SSSSSSSSSSSSSS3S3SS 


TES; 
LITERAL 


gs) 


gs) 


Size of block for ADA (without re 
Size of block for ADA (with re 


Size of header in lLongwords 
Max of above sizes 


° 
. 
e 


orn 
weer 


<«<<<~x 


_HE 
“AD 
“AD 
“MA 


DBGE XT$K 


DBGEXTS$K 
MACRO 


SIZE] 
FIELDS, 


BER 


BLOCK = BLOCK CDBGEXTS$K_MAX 
FIELD ( DBGEXTSHEA 


DBGEXTSCONTROL_ 


— 
mm 
aa 
— 
usu 
— — 
ta 
te 
ao 


DBGEXTSA 
DBGEXTSR 


oa 
ag 
o 
oe 
a 
wo 
nw 
. 
a0 
> 
co 
w 
~o 
- 
wT 
co 
o 
- — 
a 
Abe 
” 
a 
~o 
- 
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ERA 
DBGEXT $K_MIN_STATE 


Soneret ty. multiple priorities and states are valid as ‘nput when calling 

the ADA run time system but are not valid as output —* on return from 

J coke poe geek the following constants are prey ided for convenience 
Sy" Pato mitve TR the contents of the fields DBGEXT$V_STATE and 

pace xtsv RIORITY ey define the only possible values of the respective 

fields when multi pie fr orities and states are not allowed. 

Constants for DBGEXTSV_HOLD are provided for completeness. 


%((superfluous? -tbs))% 


DBGEXTSK_MAX_STATE 
DBGEXTSS_ STATE 
BGEXTSK_STATE_READY 
DBGEXTSK_STATE_ SUSPENDED 
DBGEXTSK_STATE_ TERMINATED 


DBGEXT$S_HOLD 


!' size of DBGEXT$V_STATE 
! values for DBGEXT$v_STATE 


size of DBGEXT$V_HOLD 


— —— — — — — — — — — — — — — — — — — — — — — — — — — — — — — 2 nd — — — — — — es 


Fwn-O0en 


a ee 
BVVVVVVVVDD 


SESSSESESE 
———————— 
— KKK 


8 
2) 
m 
=< 
—~ 
bad 
x 

6 


DBGEXTSK_HOLD * ¢, ' values for DBGEXT$V_HOLD 
DBGEXTSS_PRIORITY = 2, ! size of DBGEXTSV_PRIORITY 
DBGEXTSK_PRIORITY_00 = 0, ! yalues for DBGEXT$V_PRIORITY 
DBGEXTSK~PRIORITY~01 =1* 1; 
DBG —J2336 = . ¢° 
DBGEXTSK~PRIORITY~0 21° §, 
DBGEXTSK~PRIORITY~04 2° 4&4, 
DBGEXTS$K~PRIORITY~05 “Shae * 
DBGEXTSK_PRIORITY_06 = - @s 
DBGEXTSK_PRIORITY_07 = ™ Te 
DBGEXTSK~PRIORITY~08 =1°* 8, 
DBGEXTSK_PRIORITY_09 = . &, 
DBGEXTS$k~PRIORITY~10 = 1° 10, 
DBGEXTSK~PRIORITY"11 21°11, 
GEX paint ty ig s** Ve. 
DBGEXTSK_PRIORITY_1 = a * 
DBGEXTSK_PRIORITY_14 = * 1%, 
DBGEXTSK_PRIORITY_15 = > 35. 
DBGEXTSK_PRIORITY_16 = * i, 
DBGEXTSK~PRIORITY~ =1° 17. 
DBGEXTSK_PRIORITY_ ee; * 8, 
~PRIORITY_ =1°* 19, 
PRIORITY = = 2, 
IORITY eg? a, 
IORITY s1°* ¢° 
IORITY ⸗ ° — 
IORITY = 1% 24, 
IORITY sf * 25, 
IORITY s 3 * g. 
IORITY ey* 
IORITY = » 2, 
IORITY = 1* 29, 
IORITY = * 30, 
IORITY = » 313 


sevpeveveven 
WIWnononononononononuny 
WInononononononononony 2 2 2 2 


—OOOnouw 
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FACILITY CODES 


1 
i 
i The following are the possible values of the DBGEXTSV -FACILITY_ID field. 
i — ee to the different run-time system we are 

ic feating with 

' 

1 

1 


ADAS 438—BN 
PPAS_FACILITY 
SCNS-FACILITY 


'*QUES® %£((-tbs))% 
! Do PPA and SCAN have facility mnemonics and codes? Are the 
' above guesses correct? 


H 14 
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+ 


FUNCTION CODES 
The ny re the possible values of the DBGEXTS$w 45: ea — field 


when the contents of the FACILITY_ID field is ADASFACILI Thes 
a to the funct tens that Ehe ADA run-time —— Mitt be. asked to 


Summary of the defined Function codes 


DBGEXTSK_MIN_FUNCT = 1, ! For CASE bounds 
These are used 2. —** and convert task values 
DBGEXTSK_CVT_V s 


DBGEXTSK_CVT_NUM NUR-VAL UE * z. 
DBGEXTSK_NEXT_TASK © Be 


These are used to ask ADA to dtepley task information 
DBGEXT HOW_TAS 
DBGE KT SK “SHOW_STATISTICS = * 


XT$K_ SHOW" DEADLOCK = 6, 
These gre ue — * get and set various attributes of one or more tasks 
DBGEXTSK ster. ATE 27. 
—B——— = 8, 
DBGEXTSK_SET_ACTIVE 29 
DBGEXTSK~SET~TERMINAT = 16, 
Seng an = 11, 
priorit 
DBGERTSK” POET "PRIORITY = \¢- 
DBGEXTSK-SET PRIORITY = 13, 
DBGEXTSK_RESTORE_PRIORITY = 14, 
ask registers 
DBGERt $K_GET_REGISTERS 


1 
DBGEXTSK_SET_REGISTERS 1 
These ore used to control definab 
DBGEXTSK_ENABLE EVENT 1 
DBCEXTSK “DISABLE. EVENT 1 


DBGEXTSK_MAX_FUNCT 


5 
6 
le events 
Ts 
8, 


18; ' For CASE bounds 
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LITERAL 
A minimum task code is defined for CASE statement bounds. 
DBGEXTSK_MIN_FUNCT = 1, 


CVT_VALUE_NUM takes a task value and converts it to a task number. 


! 

1 

INPUT - The task value is placed in the DBGEXTSL_TASK_VALUE field. 

i OUTPUT = The task number is returned in the DBGEXTSL_TASK_NUMBER field. 
i (If the task does not exist, this function returns 

' status STSSK SEVERE) .%((TASK DOES NOT EXIST CODE? -tbs))% 
Z((VALUE IS ROT LEGAL OR ACCVIO? -tbs))% 
DBGEXTS$K_CVT_VALUE_NUM = 1, 


CVT_NUM_VALUE takes a task number and converts it to a task value. 


i INPUT - The task number is placed in the DBGEXTSL_TASK_NUMBER field. 
! OUTPUT - The task value is returned in the DBGEXTSL_TASK_VALUE field. 


(If the task does not exist, this function returns 
status STSSK_SEVERE).2((TASK DOES NOT EXIST CODE? -tbs))% 


DBGEXTSK_CVT_NUM_VALUE = 2, 


NEXT_TASK gives a task value and asks ADA to specify the ‘'next’’ task. 


: The ordering of tasks is up to the ADA run-time system. The only 

: requirement on order is that if we start with any task, and repeatedly 
! ask for the ‘‘next’’ without giving the user program control in between, 
! then we will cycle *1** all the 

! started with. If selection 


tasks and return to the task we 
criteria are imposed, then we will cycle 


! through all tasks which match that criteria. 
i INPUTS = The task value is placed in the DBGEXTSL_TASK_VALUE field. 


If the TASK_VALUE field is zero (implying the NULL task) the 
next task will be the main task of the program. 


The ALL flag is ignored, ADA will consider it on by default. 


The set of tasks to cycle through can be restricted by 
imposing a selection criteria. The PRIORITY, and/or STATE, 
and/or HOLD fields can contain values which a task must match 
to be part of the set (e.g. SHOW TASK/PRI=3/HOLD/STATE=READY). 
When such a restriction is desired, the DBGEXTSV_xxx_SPECIFIED 
bits must be set accordingly. If no restriction is desired, 
the SPECIFIED bits must be zero. A task must match all the 
criteria which are specified to be part of the set. 


————__—— 
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:%( (Multiple PRI and STATE can be given as these are bit fields -tbs))% 

! OUTPUT = The “‘next’’ task value is returned in DBGEXTSL_TASK_VALUE. 
DBGEXTSK_NEXT_TASK = 3, 

! SHOW. TASK is used to request that ADA display information about a 

: specified task. 

INPUTS = The task value is placed in the DBGEXTS$L_TASK_VALUE field. 

i The address of a print routine that ADA is to gall to displa 
i the information, is placed in the field DBGEXTSL_PRINT_ROUTIN 
; (see DBGSPRINT_ROUTINE below). 

1 

i 

i 


If the DBGEXTSV_FULL bit is set, more detailed information 
is displayed. 


ouT PUT =- none. 
DBGEXT$K_SHOW_TASK = 4, 


! SHOW_STATISTICS requests that the ADA run-time ay display 
! statistics about the overall state of the multitasking system. 


i INPUTS - The address of a print routine is given in the field 
DBGEXTSL_PRINT_ROUTINE. 


If the DBGEXT$V_FULL bit is set, more detailed information 
is displayed. 


i QUTPUT = none. 


DBGEXTSK_SHOW_STAT = 5, 


SHOW _DEADLOCK requests that the ADA run-time system display information 
about deadlocks within the multitasking system. 


INPUTS - The address of a print routine is given in the field 
DBGEXTSL_PRINT_ROUTINE. 


If the DBGEXTSV_FULL bit is set, more detailed information 
is displayed. 


OUTPUT = none. 
DBGEXT$K_SHOW_DEADLOCK = 6, 


! GET STATE inquires about the ‘'state’’ and HOLD condition of a task. The 
' state’ can be one of RUNNING, READY, SUSPENDED, TERMINATED. 
} The state codes are defined below. 


— — — — — — — — — — — — —— — — —— — — — 
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INPUT - The task value is placed in the DBGEXTSL_TASK_VALUE field. 


OUTPUTS = A code popresentin the state is returned in thex Z((V_STATE -tbs))% 
DBGEXTSW_STATE field. 


The DBGEXTSV_HOLD field is also set if the task is on HOLD. 
BGEXTSK_GET_STATE = 7, 


wer tt rt. — — 


GET_ACTIVE obtains the task value of the active task. 

(The active task is that task in whose context (stack and register set) 
DEBUG is executing. This is contrasted with the ‘visible task’ -- 

the task whose register set is sonporer tt in_use by DEBUG 

as a default for the purposes of SHOW CALLS, EXAMINE, etc.). 


1 

i 

i 

i 

i 

i 

: INPUTS - none 
i OUTPUT = The task value of the active task is returned 
in DBGEXTSL_TASK_VALUE. 

i 
i 


Z(( Cam the active task be the null task? -tbs))% 
DBGEXTSK_GET_ACTIVE = 8, 


! SET_ACTIVE requests the run-time system to switch the active 

! task to that given in DBGEXTSL_TASK_VALUE. The ‘‘long form’ DBG 

' control block is used. The esetetere provided by DEBUG in the control 
! block are those of the (currently) active task. he run-time 

' system uses these to save the registers of the active task. It 

! may also modify this register set, (currently ony the PC and PSL). 
! when this call returns, DEBUG should use the possibly-modified 

! register values as the active register set. If the PSEUDO_GO bit 
! is set, DEBUG should then perform the actions of a normal GO, 

! except that ASTs are left disabled. This ‘‘pseudo-G0' 

! will enter special run-time code that will switch-out the 

! currently active task, switch-in the requested active task, and 

: reinvoke DEBUG in that task. | (A special event code is assigned 

! to this “‘reinvoke DEBUG event’. The reinvokation event signifies 
' to DEBUG that certain components of its state are to be 

! gotten from values saved from DEBUG's prior incarnation, not those 
: at the reinvokation event. One such saved state component is 

! the “‘AST enablement’’ status - whether ASTs were enabled when 

' DEBUG was invoked.) 

! Despite these Pyrat ions. to the user typing 

! DBG> SET TASK/ACTIVE T1, it aepeers he has entered a simple command 
: immediately followed by a DBG> prompt. 

a 
' 
' 
‘ 
1 
i] 
1 


i INPUTS = The task yalue of the to-become-active task is set 
in DBGEXTSL_TASK_VALUE. 


The registers of the ——— task are stored in 


fields DBGEXT$L_RO through DBG L_PSL. 


i OUTPUTS = The register set of the new active task, as 
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modified by the run-time system, in DBGEXT$L_RO 
through DBGEXTSL_PSL. 


The DBGEXTSV_PSEUDO_GO flag may be set, in which case, 
DEBUG should perform a ‘‘pseudo go’ operation. 


DBGEXTSK_SET_ACTIVE = 9, 


SET_TERMINATE is used to cause ADA to terminate a task. It is used 
! to implement the command SET TASK/TERMINATE. 


i INPUTS - The task value is placed in the DBGEXTSL_TASK_VALUE field. 


1 

1 

1 

1 

1 

If the TASK_VALUE field is zero and the ALL flag 
} is set. then the function is done for all tasks. 
1 

1 


i OUTPUT = none 


DBGEXTS$K_SET_TERMINATE = 10, 


' SET_HOLD is used to put a task on hold or to release a task that was 
‘ previously put on hold. It is used to implement the command 

! SET TASK/HOLD which Leaves the state of a task as-is, except that each 
: task is marked HOLD. 

! INPUTS - The task value is placed in the DBGEXTSL_TASK_VALUE field. 
! 

‘ 

1 


If the TASK_VALUE field is zero and the ALL flag 
is set, then the function is done for all tasks. 


iZ(( WiLL the /ALL selection criteria be used for thr SET_xxx codes? -tbs))% 


: The desired status of HOLD is placed into the 
DBGEXTSV_HOLD field. (1 => HOLD, 0 => RELEASE) 
' 


inCCIs the request 1=>1 or 0=>0 Legal? -tbs))% 
; OUTPUT = none 
DBGEXT$K_SET_HOLD = 11, 


: GET_PRIORITY inquires about the priority of a specified task. 

: INPUT - The task value is placed in the DBGEXTSL_TASK_VALUE field. 
: OUTPUT - The priority is returned in the DBGEXTSW_PRIORITY field. 
DBGEXTSK_GET_PRIORITY = 12, 


: SET_PRIORITY is used to set the priority of a specified task. 
i INPUTS = The task value is placed in the DBGEXTSL_TASK_VALUE field. 
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f the TASK_VALUE ers My zero and the ALL flag 


s set, then the function is done for all tasks. 
The desired priority is placed in the DBGEXTSW_PRIORITY field. 
OUTPUT = none. 
BGEXTSK_SET_PRIORITY = 13, 


RESTORE_PRIORITY is used to restore the priority of a task back 
' to its normal value (as it would be without DEBUG intervention). 


i INPUTS = The task value is placed in the DBGEXTSL_TASK_VALUE field. 


i 

1 

1 

1 

1 

If the TASK_VALUE field is zero and the ALL flag 
} is set, then the function is done for all tasks. 
' 

1 


i OUTPUT - none. 


DBGEXTSK_RESTORE_PRIORITY = 14, 


hence, this call is invalid for the active task. 
A return status of STSSK_SEVERE is returned. 


: GET_REGISTERS is used to obtain the register set of a task. 

: INPUT - The task value is placed in the DBGEXTSL_TASK_VALUE field. 
! OUTPUTS = The register values are returned in the DBGEXTSL_RO 

: through DBGEXTSL_PSL fields. 

: NOTE: Only DEBUG knows the register set of the active task 

' 

' 


DBGEXTSK_GET_REGISTERS = 15, 

! SET_REGISTERS is used to change the register values of a task. 

This may be needed, for example, in SET TASK T;DEPOSIT RS = 0;G60 

i INPUTS = The task value is placed in the DBGEXTSL_TASK_VALUE field. 
i The register values are placed in the DBGEXTSL_RO 

: through DBGEXTS$L_PSL fields. 

OUTPUT = none. 

i NOTE: Only DEBUG knows the register set of the active task 

: hence, this call is invalid for the active task. 

A return status of STSSK_SEVERE is returned. 


DBGEXTSK_SET_REGISTERS = 16, 


! ENABLE_EVENT is used during processing of a ‘SET BREAK/EVENT="" or 


DBGEXT.REQ; 1 


! "SET TRACE/EVENT="" command to enable reporting of a given kind of event. 


INPUTS = The DBGEXTSL_EVENT_ID field contains a code identifying 
the event being enabled. The possible values of this 
code are defined below. 


The DBGEXTSL_TASK_VALUE field contains a task value further 
gyal tying the evént being enabled. This may be zero 
f the “ALL” flag is Lit. 


For example, : 

if we are enabling ‘‘task termination’ and we supply a 
task value, then we only want to break on termination of 
that task. If we enable ‘‘task termination’ events and 
set the ALL flag, we want to be notified of any 

task termination. 


OUTPUT = none 
DBGEXT$K_ENABLE_EVENT = 17, 


DISABLE_EVENT is used during process tne of a ‘CANCEL BREAK/EVENT="" or 

: a TRACE/EVENT="" command to disable reporting of a given kind of 

i . 

! INPUTS - The DBGEXTSL_EVENT_ID field contains a code identifying 

; the event being disabled. The possible values of this 

; code are defined below. 
i The DBGEXTSL_TASK_VALUE field contains a task value further 
' ualifying the evént being disabled. This may be zero 

f the "‘ALL"’ flag is Lit. 

OUTPUT = none 


DBGEXTSK_DISABLE_EVENT = 18, 


: A maximum task code is defined for CASE statement bounds. 
DBGEXT$K_MAX_FUNCT = 18; 
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COMPLETION STATUS 


The run time 78 has two means of providing a completi 
return value of the function and the contents of DBGEXTSL 


Function Return Value -- 


0 $s -- the 


-c 


The run time pyeten should, as its first action, attempt to read and verify 
the field DBGEXTSV_FACILITY_ID in DBGEXTSCONTROL_BLOCK. Ops tonal ty. it may 
also PROBE the confrol block for read/writability. If the FACILITY_ID is 
correct, the run time system should eventually return: 


STSS$K_SUCCESS - service successfully completed 
Otherwise, the run time system should immediately return: 
STSSK_SEVERE - service failed 


This helps to insure that an incorrect External Control Block will be 
detected before it is written to. 
Contents of DBGEXTSL_STATUS - 
ALL other status and error conditions will be placed in the STATUS field of 
the control block. The possible values of the STATUS field are a composite 
of aoser rey level and wossege number. Only two severity values are used. 
They are given by STSS$V_SEVERITY: 

STSS$K_SUCCESS - service successfully completed 
In this case the message number (STS$V_MSG_NO) is zero. 

STSSK_ ERROR = service failed 


In this case the message number (STS$V_MSG_NO) is one of the following: 


LITERAL 


DBGEXTSK_FUNCTION_NOT_IMP = 0, 

The function requested is not implemented by the facility. 
DBGEXTSK_TASK_NOT_EXIST <1, 

i Task number cannot be translated to a task value because the task does 
! not exist. Or task value does not point to a currently existing task 
! (this cannot always be detected). 

DBGEXTSK_TASK_IS_ACTIVE = 2, 


i Returned on a SET_REGISTER or GET_REGISTER function for the active task. 
! The run time system cannot access the registers of teh active task. 


DBGEXT$K_TASK_IS_NULL = 3; 
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' 
! Returned on a SET_ACTIVE function for the null task. 


—— —— — — 
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PRINT ROUTINE INTERFACE 
The as defines how to use the DEBUG print routine whose address 
is given in the DBGEXTSL_PRINT_ROUTINE field. 
ND 
DBGSPRINT_ROUTINE = .control_block C DBGSL_PRINT_ROUTINE J; 


DBGSPRINT_ROUTINE ( NEW_LINE 
—J PRINT, 


FAO-ARG_2 
FAO-ARG_n) : NOVALUE 


NEW_LINE = this can have one of two values: 


° 


0 = Place the given string in the output buffer. 
1 - If the given string is non-zero, first place it in the 
buffer. In all cases, output the buffer to the screen. 


STRING_TO_PRINT 
oa is a Prater to a counted ascii string 
E.g.. UPLIT (ZASCIC ‘Output this text 
This may be zero if the ACTION_CODE is ‘'NEWLINE'’. 


There may be FAO arguments yao tn the string. 
The string ae may contain embedded FAO commands 
such as ‘'AC "!ISL*, and so on. 


iZCCFIXUP = THIS EXTENSION IS NOT GOOD!! -tbs))% 


In addition, there will be a eon oct 2 nae extension 

to FAO which can be used for i rg My ng addresses. 

There will be a new command '! for mbolize address’. 

This indicates that the corresponding FA argument 

H — —— It's symbolization is to be embedded into 
e string. 


FAO_ARG1 through FAO_ARGn - optional parameters for FAO arguments. 
Example: suppose FOO\L is located at address 200. Then: 


DBGSPRINT_ROUT INE srg i hee NEWLINE, : 
(ZASCIC ‘Task switch at location !SA"), 


This would output: 
"Task switch at location FOO\L" 
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EVENT ID 


i The following define the —2*6 values of the DBGEXTSL_EVENT_ID field. 
5 vaaee are the predefined events t 


DBGEXTSK_MIN_EVENT_CODE 
DBGEXTSK_ INVOKE _DEBUG 


posers ~TASK_ACTI 
DBGEXTSK_TASK_S 
DBGEXTSK_T 6 
DBGEXTSK_TASK_SWITCH-TO 
DBGEXTSK_TASK_ TERMINATION 


: Ada specific tasking codes: 
BBGEXTSK _TASK_ABORT_TERM 


2 
— 
4 
t 
“4 
> 
nw" 
‘a x 
4 
> m 
3 
o 
m 
vw 
’ 
2 
m 
2 
— 
nunnnn 


DBGEXT$K~TASK~SELECT 
DBGEXTSK_MAX_EVENT_CODE 
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hat we can break or trate on.” 


Unconditional DEBUG invokation 


First transition of a task to RUNNING 
Transition from RUNNING to SUSPENDED 
Transition from RUNNING to some state 
Transition from some state to RUNNING 
Any kind of termination 


Termination by abort 

Termination by unhandled exception 
Exception propeget tae ¢ out of rendezvous 
Executing an entry cal 

Executing an accept 

Executing a select 


! 
i 
i 
: 
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EVENT CONTROL BLOCK 


The Event Control Block is the data structure snot the ADA (or other) 
facility passes to DEBUG when it signals that a given event has occured. 


For example, if you do a SET BREAK/ADAEVENT=TASK_SWITCH_TO, then 
when a task switch occurs, the ADA run-time system will pignal the special 
signal DBGS_EVENT. A pointer to an “Event Control Block” is passed 
as the ‘FAO argument’ of DBGS_EVENT. (E.g. 
LIBSSIGNAL (DBGS_EVENT, 1, .EVENT anTRaE BLOCK). (Note that this 
condition cannot preperty be an SS$ condition because they are not 
allowed to have FAO arguments other than PC and ty 

(except for the hardware conditions). Hence, the facility DBG was chosen. 
This condition is a DEBUG-defined condition that anyone can 
signal. The FAO count of 1 is required so that the message conforms 
to a tegat format for a 2 vector.) agen = proper use of the 
SEVERITY field and the NOMESSAGE bit in the condition, the 
Signaller can be assured that events will be 

reflected” by Traceback should DEBUG not be * 

into the image (for some reason). So there rea are no 
restrictions on when this condition can be signalled. 


The control block contains a code indicating the facility 

that has originated the event and another code to indicate what event 

~~ a tet It also contains message text to be output announcing 
e event. 


The following illustrates the Event Control Block: 


ILLIIA 
1 neaenran seit vent io 
— ⏑— — 
Sf — 
— J—————————————— WNT ARG COUNT 
> | DBGEXTSA_EVNT_ARG_VECT 


' 
' 
' 
Peres montana reo senor eee woe Sees swan een eereaone san aewen > 


PEL POCERTOE VENT FSELDS = 


DBGEXTSL_EVNT_FACILITY_ID 
DBGEXTSL~EVNT~EVENT_ID 

DBGEXTSL~EVNT~F LAGS 
DBGEXTSV~EVNT-MORE TEXT 
DBGEXTSV~EVNT_REENTRY 


DBGEXTSL_EVNT_MESSAGE_TXT 
DBGEXTS$L~EVNT—ARG_ COURT 
DBGEXTSA_EVNT_ARG_VECT 


“uu 
eCrTr 
ooo - 00 


—— 
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LITERAL 
DBGEXTSK_EVNT_BASE_SIZE = 5; 


MAC 
C 


T 


NUM_ARGS) = 


RO 
DBGEXTSEVENT CONTROL B 
8 Zee WUR_ARGS »LONG) 


LOCK ( 
LOCK COBGEXTS$K GASE SI 
FIELD (DBGEXTSEONT_FTIEL 


! Explanation of fields: 


FACILITY_ID field: The code for the ABD S signal ing the 
event. If the CUST_DEF bit is set the 
event is a ‘user event’’. Otherwise, the 

only supported codes are ADA, PPA, and 

scan. 


EVENT_ID field: This field contains the event code. 
Event codes are numbered from 1 within 
each facility. Event code 0 is 
reserved in all facilities. It represents 
the unconditional event, that is, 
unconditional DEBUG entry. If the 
EVENT_ID field is zero, the REENTRY bit 
is checked. 


MESSAGE _TXT field: This is a pointer to a counted ascii were. 
The string represents a message to be printed 
when the event occurs and is fomatted as an 
fao control etring - The string may take FAO 
arguments. The str ng may also contain the 
DEBUG extension to FAO, *!SA‘, in order to 
symbolize an address. fhis extension is 
described above. NOTE: if this field is 0, 
it indicates that there is no message. 


ARG_COUNT field: Count of the number of FAO arguments that go 
with the text. 

ARG_VECT field: A vector of FAO arguments. 

MORE_TEXT flag: If this flag is TRUE, it indicates that DEBUG 


is to return centres at the point of the signal 

after — ng the message. This is to be used 
for output of multi-line messages. (l.e., the 

run-time system should then resignal the event with 

25* Line of message text in the MESSAGE_TXT 
ield). 


REENTRY flag: If this flag is TRUE, then this event is a 
DEBUG-reetnry event that has occurred after a 
PSEUDO_GO. DEBUG is thereby instructed 
to restore certain components of its state 
from the values hey had at DEBUG's Last 
incarnation (e.g. AST enablement). 


25 
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REGISTERING EVENTS WITH DEBUG 


DEBUG'’s event handling feature is available to user prppress as 
well as Digital software. DEBUG maintains an event table 
for each facility that chooses to register its events with DEBUG. 


Registering an event with —* is very simple. The facility 
need only signal the following signal after DEBUG has 
been invoked in an image: 


LIBSSIGUM (OBES REGISTER EVENTS, 

first_event_condition, 

second_event_condit on, 
etc. 


A List of event conditions is chained below a master condition 
of DBGS_REGISTER_EVENTS. This signal may be raised as many 
times as desired to add more events to DEBUG's event table. 
Since DEBUG derives the facility number from the event 
condition, events for different facilities may be 

registered with the same signal. 


The event conditions sppeer ing in the message vector must 
be defined in the facilities message file. The string 
defined in the message file is the string that DEBUG 

will use to name the event. 


For example, suppose we wish to add an event of PLIS_TASK_SWITCH. 
The following would do it: 


1. Add to PLI's message file: 
PLIS_FACILITY = xxx 
TASK_SWITCH *“*TASK_SWITCH" 


2. Register the event with DEBUG 
LIBSSIGNAL (DBGS_REGISTER_EVENTS, PLIS_TASK_SWITCH) 


After the registration, any user can then type 
SET BREAK/EVENT=PLI$_TASK_SWITCH 
A command SET EVENT/FACILITY="PLI$_"* can be used so the facility 
8 he can be omitted, e.g. SET BREAK/EVENT=TASK_SWITCH 
his will then not be confused with an Ada task Switch. 
SET EVENT/NOFACILITY will eliminate the automatic prfixing of 
event names. 


To 14 the registration of events by facilities, any 
facility should provide an ve point that users can 
call from the DEBUGGER to ioad the events of that facility. 
To load PLI*s events, then, a user would merely type 


DBG> CALL PLIS$_LOAD_€VENTS 


** Obviously, Ada’s events should be registered with this same 
general mechanism 
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